QuickDraw 3D™ 1.1 WWDC DR - Win32 Platform Preliminary Developers' Release 

Preliminary Release Notes - May 2, 1996

This special release includes only the debug build of QuickDraw 3D for Win32. The release version DLLs will be included in a future developers' release. Since this is a debugging, development build it does not represent the type of performance you can expect in an optimized, non-debugging release. 

This is a preliminary development release. It is intended for evaluation purposes only. No part of this release may be redistributed without permission from Apple Computer. 

Welcome to QuickDraw 3D!  

QuickDraw 3D is a platform independent 3D graphics library developed by Apple Computer.  Enclosed, you will find the 1.1 WWDC DR release of QuickDraw 3D for Win32.

QuickDraw 3D goes beyond providing 3D graphics, it provides an integrated solution both for the end user and for developers.  QuickDraw 3D encompasses a standard file format (3DMF), acceleration layer, input architecture, high level geometries, and extensibility.

QuickDraw 3D is a library for PowerPC™ based computers running the MacOS and Pentium™ based computers running Windows 95™ or Windows NT™ 3.51.  The API is in C, with support for development using C++.  QuickDraw 3D allows for immediate mode and retained rendering.  The API is object based and provides a large number of geometry types.  The file format accommodates both text and binary modes, with encoding for endianess so that files can be transported to other platforms and across the Internet. 3DMF parser code for several different platforms is available from our Web page at http://www.info.apple.com/qd3d/.

QuickDraw 3D for Win32 System Requirements
•	Pentium processor
•	Windows 95 or Windows NT 3.51
•	A video board providing 256 color (8-bit) at 640x480 resolution. High Color (16-bit) or True Color (24-bit or 32-bit) video highly recommended.

Development System Requirements
•	Microsoft Visual C++ 4.0 or 4.1 
•	MSVCR40D.DLL - the debug version of C runtime DLL which is included with Visual C++ 4.0 and 4.1

Functionality
•	Pixmap Draw Context Only
Only the pixmap draw context is supported in this developer release of the QuickDraw 3D. The implication of this is that your application will be responsible for blitting the draw context to the screen. See "Implementing Double Buffering Using Pixmap Draw Context and GDI" below.

A Win32 specific draw context will be fully supported in a forthcoming developer release.

•	The QuickDraw 3D Pointing Device Manager
The QuickDraw 3D Pointing Device Manager API is not supported in the Win32 version of QuickDraw 3D.

Using this QuickDraw 3D Win32 Preliminary Developer Release
•	Copy the contents of the QuickDraw 3D preliminary Win32 release to your hard drive.
•	Set you Lib and Include paths to reference the QuickDraw 3D Lib directory and Interfaces directory respectively. (Under Visual C++ this can be done from the Tools|Options|Directories dialog panel.) 
•	Set your Path to reference the QuickDraw 3D Lib directory where the QuickDraw 3D DLLs are located or copy these DLLs to your Windows\System folder (Win95) or Windows\System32 directory (NT).

Lib, Include and Path can be also be set using environment variables (in Autoexec.bat on Win95 or in the System control panel on NT).
example: 
   Set LIB = %LIB%;c:\QD3D\LIB
   Set INCLUDE = %INCLUDE%;c:\QD3D\Interfaces
   Set PATH = %Path%;c:\QD3D\LIB

Implementing Double Buffering Using Pixmap Draw Context and GDI
QuickDraw 3D applications using this developer release must use the generic pixmap draw context. A native Win32 draw context will be fully supported in a future developer release.

The basic method for managing a pixmap draw context is demonstrated in the enclosed QD3DSample application project. It consists of two main steps: Creating a new draw context for a view and rendering.

Creating a draw context for a view:
•	Create a memory device context compatible with the view window's DC and store a reference to it.
	hdc = GetDC(theDocument->fWindow);
	theDocument->fMemoryDC = CreateCompatibleDC(hdc);

•	Create an 16 or 32 bit device independent bitmap (DIB) and select it into the memory device context.
	bitmapInfo.bmiHeader.biSize = sizeof(BITMAPINFOHEADER);	
	bitmapInfo.bmiHeader.biWidth = theDocument->fWidth;	
	bitmapInfo.bmiHeader.biHeight = -theDocument->fHeight; // note: negative for top-down DIB	
	bitmapInfo.bmiHeader.biPlanes = 1;
	if ( GetDeviceCaps(hdc, BITSPIXEL) == 32 )
		bitmapInfo.bmiHeader.biBitCount = 32;
	else
		bitmapInfo.bmiHeader.biBitCount = 16;	
	bitmapInfo.bmiHeader.biCompression = BI_RGB;	
	bitmapInfo.bmiHeader.biSizeImage = 0;	
	bitmapInfo.bmiHeader.biXPelsPerMeter = 0;	
	bitmapInfo.bmiHeader.biYPelsPerMeter = 0;	
	bitmapInfo.bmiHeader.biClrUsed = 0;	
	bitmapInfo.bmiHeader.biClrImportant = 0;	
	theDocument->fBitmap = CreateDIBSection(hdc, &bitmapInfo, DIB_RGB_COLORS,	
		&theDocument->fBitStorage, NULL, 0);	
	SelectObject(theDocument->fMemoryDC, theDocument->fBitmap);

•	Create a new pixmap draw context which is parametrized to match the DIB. Set the pixmap draw context's image data pointer to the DIB's bitmap data. The draw context's doubleBufferState flag should be false.
	myDrawContextData.clearImageMethod = kQ3ClearMethodWithColor;
	myDrawContextData.clearImageColor = ClearColor;
	myDrawContextData.paneState = kQ3False;
	myDrawContextData.maskState = kQ3False;
	myDrawContextData.doubleBufferState = kQ3False; // the app is doing the double buffering
		/* create a TQ3Pixmap */
	aPixmap.width = theDocument->fWidth;
	aPixmap.height = theDocument->fHeight;
	aPixmap.image = theDocument->fBitStorage;  //fBitStorage is bitmap data from the DIB
	if (bitmapInfo.bmiHeader.biBitCount == 32)
	{
		aPixmap.rowBytes = aPixmap.width * 4;
		aPixmap.pixelSize = 32;
		aPixmap.pixelType = kQ3PixelTypeRGB32;
	}
	else
	{
		aPixmap.rowBytes = (aPixmap.width * 
			(bitmapInfo.bmiHeader.biBitCount/8));
		aPixmap.rowBytes = (aPixmap.rowBytes + 3) & ~3L; // make it long aligned
		aPixmap.pixelSize = 16;
		aPixmap.pixelType = kQ3PixelTypeRGB16;
	}
	aPixmap.bitOrder = kQ3EndianLittle;  
	aPixmap.byteOrder = kQ3EndianLittle; 
		/* set up the pixmap draw context */
	myPixmapDrawContextData.pixmap = aPixmap;
	myPixmapDrawContextData.drawContextData = myDrawContextData;
	myDrawContext = Q3PixmapDrawContext_New(&myPixmapDrawContextData);

•	Set the pixmap draw context as the draw context for the view and dispose of the draw context.
	Q3View_SetDrawContext(myView, myDrawContext);
	Q3Object_Dispose( myDrawContext );

•	Be sure to set the renderer associated with your view to use double buffer bypass. (Remember your application is performing the double buffering).
	myRenderer = Q3Renderer_NewFromType(kQ3RendererTypeInteractive;
	Q3View_SetRenderer(myView, myRenderer;
	Q3InteractiveRenderer_SetDoubleBufferBypass( myRenderer, kQ3True);
	Q3InteractiveRenderer_SetPreferences(myRenderer, kQAVendor_BestChoice, 0);

Rendering (typically in response to WM_PAINT)
•	Do your rendering loop.
	hdc = GetDC(theDocument->fWindow);
	Q3View_StartRendering(theDocument->fView );	
	do {	
		Q3Shader_Submit( theDocument->fIllumination, theDocument->fView );	
		Q3Style_Submit( theDocument->fInterpolation, theDocument->fView );	
		Q3Style_Submit( theDocument->fBackFacing, theDocument->fView );	
		Q3Style_Submit( theDocument->fFillStyle, theDocument->fView );	
		Q3MatrixTransform_Submit( &theDocument->fRotation, theDocument->fView );	
		Q3DisplayGroup_Submit( theDocument->fModel, theDocument->fView );	
	} while (Q3View_EndRendering(theDocument->fView) == kQ3ViewStatusRetraverse );	

•	Copy the data from the memory DC to the window using BitBlt.
	BitBlt(hdc, 0, 0, theDocument->fWidth, theDocument->fHeight,	
			theDocument->fMemoryDC, 0, 0, SRCCOPY);					
	ReleaseDC(theDocument->fWindow, hdc);				

Library Linking Issues
This preliminary developer release includes only the debugging version of QuickDraw 3D as a DLL. This library requires MSVCR40D.DLL - the debug version of the Visual C++ 4.x C-runtime library DLL.

What's In This Release?
In the Lib folder
 QD3D_D.DLL - the debug version of the QuickDraw 3D 1.1 core library,
        dependencies: MSVCR40D.DLL, RAVE.DLL, MSVCRT40.DLL
 QD3D_D.LIB - the import library for QD3D_D.DLL

 MSVCRT40.DLL - the releae C-Runtime library DLL (from Visual C++ 4.1)

 RAVE.DLL - a preliminary release build of QuickDraw 3D Accelleration library version 1.1
         dependencies: MSVCRT40.DLL

 3DViewer_d.DLL - a preliminary debug build of the 3D Viewer for Windows
        dependencies: QD3D_D.DLL, MSVCR40D.DLL, RAVE.DLL, MSVCRT40.DLL
 3DViewer_d.LIB - the import library for 3DViewer_d.DLL 

In the Interfaces folder
  The public interfaces for QD3D_D.DLL and 3DViewer_d.DLL 

In the Samples folder
  QD3DSample - a simple application which demonstrates using the QuickDraw 3D core library to load and display 3D data. This sample implements double buffering using a pixmap draw context as described above.

  ViewerSample - a simple example of using the QuickDraw 3D Viewer Controller in a Win32 application.

Documentation
The "Documentation" subdirectory of this release includes Adobe Acrobat PDF versions of the QuickDraw 3D reference "3D Graphics Programming With QuickDraw 3D", the preliminary "3D Metafile Reference" as well as two introductory articles from Apple technical journal develop. Even though the develop articles discuss using QuickDraw 3D with the MacOS most of the material contained therein is equally applicable to the Win32 version of QuickDraw 3D. 

The Adobe Acrobat Reader for Windows is included in the "Documentation" directory.

"3D Graphics Programming With QuickDraw 3D" is available from Addison-Wesley Publishing Company. ISBN 0-201-48926-0

Redistribution
No part of this Preliminary Developer Release may be redistributed at this time.

Feedback
Send your comments and feedback on this release to S.HOPWOOD@AppleLink.apple.com. 

In the event that you have to report a problem please be sure to specify that you are using this WWDC preliminary Win32 developer release and be sure to include a complete description of your PC system configuration including video board and video driver configuration.

Apple Computer's 3D technologies evangelist, Shawn Hopwood (S.HOPWOOD@AppleLink.apple.com) is eager to work with developers.  Contact Shawn with details of your product.

Thanks for choosing QuickDraw 3D, and good luck with your development efforts!!

The QuickDraw 3D team.